package org.uniview.common.service.transaction;

/**
 * The Transaction manager allow an service to manage transaction 
 * boundaries. Typically, It manages DAOs' transactions to be 
 * committed and ended (possibly rolled back).
 * <p>For examples:</p>
 * <pre>
 * PersonDao personDao = daoManager.getDao(PersonDao.class);
 * <b>try {</b>
 *   // Calling startTransaction() to manage the transactions manually.
 *   <b>transactionManager.startTransaction();</b>
 *   personDao.insertPerson (person);
 *   person.setLastName("Begin");
 *   personDao.updatePerson (person);
 *   // Commit all active transactions in all contexts
 *   <b>transactionManager.commitTransaction();</b>
 * <b>} finally {</b>
 *   // End all active transactions in all contexts and rollback if necessary.
 *   <b>transactionManager.endTransaction();</b>
 * <b>}</b>
 * </pre>
 * @author James Gao
 * @version 1.0 2007-1-10
 */
public interface TransactionManager {

	  /**
	   * Starts a new transaction scope managed by this TransactionManager.
	   * <p>If this method isn't called, then all DAO methods use
	   * "autocommit" semantics.</p>
	   */
	  public void startTransaction() throws TransactionException;

	  /**
	   * Commits all transactions currently started for all contexts
	   * managed by this TransactionManager.
	   */
	  public void commitTransaction() throws TransactionException;

	  /**
	   * Ends all transactions currently started for all DAO contexts
	   * managed by this TransactionManager. 
	   * <p>If any transactions have not been successfully committed, 
	   * then those remaining will be rolled back.</p>
	   */
	  public void endTransaction() throws TransactionException;
	  
}
